3D Graphics Programming with QuickDraw 3D 1.5.4

Metafile External References

Suppose E is a metafile that contains an object R that you wish to reference from another metafile M. E must have an entry to object R in its Table of Contents (TOC). There are two ways to achieve this: you can write E out in database mode or make sure that R is written out twice in E while E is in normal mode.

With such a metafile E, the first step in writing object R out as an external reference is to read R from E. You must open E using the UnixPath storage class. While E is still open for reading, call Q3File_MarkAsExternalReference on R and the TQ3FileObject associated with E. This marks R as an object that will always be written out as an external reference. This means that whenever a Q3..._Submit call is made on the object in a write loop, an external reference object is written out that specifies the location of the object in E.

The process of reading metafiles containing external references is transparent to the user, so long as no problems arise. If the location of the object is not given correctly by the UNIX pathname, then the read call on the external reference object will return NULL . Also, the file object containing the externally referenced object must not currently be open for reading or writing.

The external reference object contains two pieces of information: the name (or pathname) of the metafile that's being externally referenced (E in this example), and the reference ID of the object R.

Once a file containing external references has been created, calling Q3File_GetExternalReferences returns the names of the files that are externally referred to by M. If no files are externally referred to, the call returns NULL . If one or more files are externally referred to, Q3File_GetExternalReferences returns a group that contains one Q3String object for each external reference object in the metafile. The Q3String object contains the name (in general, the pathname) of the file in question. Because one Q3String object is produced per external reference, it is possible for the same name to appear in several Q3String objects.

Routines that let you access and manipulate external references in metafiles are described in "Custom File Object Routines" . For general information about metafiles, see the document QuickDraw 3D 1.5 Metafile Reference.